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ABOUT SPINSIDE MACINTOSH 


SpInside Macintosh is an attempt at putting the entire contents of "Inside 
Macintosh" into a useable electronic format. It has been inspired by developer 
feedback on the Technical Notes Stack, "Phil & Dave's Excellent CD", and by the 
need for an electronic version of our beloved "Inside Mac." At this stage, 
SpInside Macintosh is nothing more than a rough development PROTOTYPE. 


It combines "Inside Macintosh" Volumes I-V into a single, sometimes coherent, 
electronic source. This text has not been rewritten for this format (i.e., we 
even left the Lisa references), but we did try to correct small things where we 
could. Information from Volumes IV and V has been inserted where deemed 
appropriate into the original text; however, some paragraphs may seem out of 
place. We tried to note machine- or system software-dependent references where 
the text may not have been clear, and we also incorporated an interim chapter 
on the Script Manager 2.0 and completely replaced the Sound Manager chapter. 
Hopefully, we haven't introduced any new errors to the original text. 


The chapters are numbered according to their order in this stack, and other 
than navigation through this stack, these numbers have neither a correlation to 
the original chapter numbers nor any other significance. 


We're distributing SpInside Macintosh as a development prototype because we 
feel it is more important for you to have it to use right now than to wait for 
us to finish a release-quality version. We also really want your feedback on 
it, so you, the real users of "Inside Macintosh," can have a hand in designing 
your ideal electronic version instead of us telling you how it should be. Tell 
us what you like and dislike about the format, organization, and usefulness (or 
lack thereof). It is this feedback, both good and bad, that will ultimately 
decide the future of SpInside Mac and its derivatives. 


Thanks for your support and especially for your patience. Have at it! 
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Inside Macintosh: The Book 


Inside Macintosh is a five-volume set of manuals that tells you what you need 
to know to write software for the Macintosh family of computers. Although 
directed mainly toward programmers writing standard Macintosh applications, 
Inside Macintosh also contains the information needed to write simple utility 
programs, desk accessories, device drivers, or any other Macintosh software. It 
includes: 


e 


e 


e 


the user interface guidelines for applications on the Macintosh 

a complete description of the routines available for your program 
to call (both those built into the Macintosh and others on disk), 
along with related concepts and background information 

a description of the Macintosh 128K, 512K, and Plus hardware 


It does not include information about: 


e 


e 


Programming in general. 
Getting started as a developer. For this, write to: 


Developer Programs 

Apple Computer, Inc. 

20525 Mariani Avenue, M/S 75-2C 
Cupertino, CA 95014 

(408) 974-4897 


Any specific development system, except where indicated. You'll 
need to have additional documentation for the development system 
you're using. 

The Standard Apple Numerics Environment (SANE), which your program 
can access to perform extended-precision floating-point arithmetic 
and transcendental functions. This environment is described in the 
Apple Numerics Manual. 

A description of Macintosh family hardware since the Macintosh Plu 
Refer to the "Macintosh Family Hardware Reference" for this inform 
A description of card architecture and programming techniques for 
slot-based Macintosh systems. Refer to "Designing Cards and Drive 
for the Macintosh II and Macintosh SE" for this information. 


Ss. 
ation. 


rs 


You should already be familiar with the basic information that's in Macintosh, 
the owner's guide, and have some experience using a standard Macintosh 
application (such as MacWrite). 
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The Languages 


The routines described in this book are written in assembly language, but (with 
a few exceptions) they're also accessible from higher-level languages. The 
first four volumes of Inside Macintosh document the interfaces to these 
routines on the Lisa Workshop development system. A powerful new development 
system, the Macintosh Programmers Workshop (MPW), is now available. Volume V 
documents the MPW Pascal interfaces to the routines and the symbolic 
identifiers defined for assembly-language programmers using MPW. These 
identifiers are usually identical to their Lisa Workshop counterparts. If 
you're using a different development system, its documentation should tell you 
how to apply the information presented here to that system. 


Inside Macintosh is intended to serve the needs of both high-level language and 
assembly- language programmers. Every routine is shown in its Pascal form (if 
it has one), but assembly-language programmers are told how they can access the 
routines. Information of interest only to assembly-language programmers is set 
apart and labeled so that other programmers can conveniently skip it. 


Familiarity with MPW Pascal (or a similar high-level language) is recommended 
for all readers, since it's used for most examples. MPW Pascal is described in 
the documentation for the Macintosh Programmer's Workshop. 


What's in Each Volume 


Inside Macintosh consists of five volumes. Volume I begins with the following 
information of general interest: 


* a "road map" to the software and the rest of the documentation 

¢ the user interface guidelines 

* an introduction to memory management (the least you need to know, 
with a complete discussion following in Volume IT) 

* some general information for assembly-language programmers 


It then describes the various parts of the User Interface Toolbox, the software 
in ROM that helps you implement the standard Macintosh user interface in your 
application. This is followed by descriptions of other, RAM-based software 
that's similar in function to the User Interface Toolbox. (The software 
overview in the Road Map chapter gives further details.) 


Volume II describes the Operating System, the software in ROM that does basic 
tasks such as input and output, memory management, and interrupt handling. As 
in Volume I, some functionally similar RAM-based software is then described. 


Volume III discusses your program's interface with the Finder and then 
describes the Macintosh 128K and 512K hardware. A comprehensive summary of all 
the software is provided, followed by some useful appendices and a glossary of 
all terms defined in Inside Macintosh. 


Volume IV is a companion to the first three volumes that gives specific 
information on writing software to take advantage of the features of the 
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Macintosh Plus and the Macintosh 512 enhanced. A familiarity with the material 
presented in the first three volumes is assumed, since most of the information 
presented in Volume IV consists of changes and additions to that original 
material. This volume also introduces four additional chapters-"The System 
Resource File", "The List Manager", "The SCSI Manager", and "The Time Manager". 


Volume V presents new material specific to the Macintosh SE and Macintosh II 
computers. Familiarity with the material presented in the first four volumes 
is assumed, since most of the information presented in Volume V consists of 
changes and additions to that original material. 


Version Numbers 


This edition of SpInside Macintosh describes the following versions of the 
software: 


¢ version 105 of the ROM in the Macintosh 128K or 512K 
e version 112 of the ROM image installed by MacWorks in the Macintosh XL 
¢ version 117 ($75) of the ROM in the Macintosh Plus and 
Macintosh 512K enhanced 
* version 118 ($76) of the ROM in the Macintosh SE 
¢ version 120 ($78) of the ROM in the Macintosh II 
* version 1.1 and 2.0 of the Lisa Pascal interfaces and 
the assembly-language definitions 
* version 2.0 of the MPW Pascal interfaces and 
the assembly-language definitions 


Some of the RAM-based software is read from the file named System (usually kept 
in the System Folder). This manual describes the software in the System file 
whose creation date is May 2, 1984, System file version 3.2 whose creation date 
is June 4, 1986, and System file version 4.1. In certain cases, a feature can 
be found in earlier versions of the System file; these cases are noted in the 
text. 


Compatibility 


Version 117 ($75) of the ROM, also known as the 128K ROM, is provided on the 
Macintosh 512K enhanced and Macintosh Plus. 


Note: A partially upgraded Macintosh 512K is identical to the Macintosh 
512K enhanced, while a completely upgraded Macintosh 512K includes 
all the features of the Macintosh Plus. 


Version 105 ($69) of the ROM (the version described in the first three volumes 
of Inside Macintosh), also known as the 64K ROM, is provided on the Macintosh 
128K and 512K. 


Most applications written for the 64K ROM run without modification on machines 
equipped with the 128K ROM. Applications that use the routines and data 
structures found in the 128K ROM, however, may not function on machines 
equipped with the 64K ROM. 
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Programmers may wish to determine which version of the ROM is installed in 
order to take advantage of the features of the 128K ROM whenever possible. You 
can do this by checking the ROM version number returned by the Operating System 
Utility procedure Environs; if the version number is greater than or equal to 
117 ($75), it's safe to use the routines and data structures described in this 
volume. 


Assembly-language note: A faster way of determining whether the 128K ROM 
is present is to examine the global variable Rom85 
(a word); it's positive (that is, the high-order 
bit is 0) if the 128K ROM is installed. 
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A HORSE OF A DIFFERENT COLOR 


On an innovative system like the Macintosh, programs don't look quite the way 
they do on other systems. For example, instead of carrying out a sequence of 
steps in a predetermined order, your program is driven primarily by user 
actions (such as clicking and typing) whose order cannot be predicted. 


You'll probably find that many of your preconceptions about how to write 
applications don't apply here. Because of this, and because of the sheer volume 
of information in Inside Macintosh, it's essential that you read the Road Map 
chapter. It will help you get oriented and figure out where to go next. 


@ SpInside Macintosh * Version 1.0 * November 1989 * Apple Computer 
PREFACE ¢ 8 of 11 


THE STRUCTURE OF A TYPICAL CHAPTER 


Most chapters of Inside Macintosh have the same structure, as described below. 
Reading through this now will save you a lot of time and effort later on. It 
contains important hints on how to find what you're looking for within this 
vast amount of technical documentation. 


Every chapter begins with a very brief description of its subject and a list of 
what you should already know before reading that chapter. Then there's a 
section called, for example, "About the Window Manager", which gives you more 
information about the subject, telling you what you can do with it in general, 
elaborating on related user interface guidelines, and introducing terminology 
that will be used in the chapter. This is followed by a series of sections 
describing important related concepts and background information; unless 
they're noted to be for advanced programmers only, you'll have to read them in 
order to understand how to use the routines described later. 


Before the routine descriptions themselves, there's a section called, for 
example, "Using the Window Manager". It introduces you to the routines, telling 
you how they fit into the general flow of an application program and, most 
important, giving you an idea of which ones you'll need to use. Often you'll 
need only a few routines out of many to do basic operations; by reading this 
section, you can save yourself the trouble of learning routines you'll never 
use. 


Then, for the details about the routines, read on to the next section. It gives 
the calling sequence for each routine and describes all the parameters, 
effects, side effects, and so on. 


Following the routine descriptions, there may be some sections that won't be of 
interest to all readers. Usually these contain information about advanced 
techniques, or behind the scenes details for the curious. 


For review and quick reference, each chapter ends with a summary of the subject 
matter, including the entire Pascal interface and a separate section for 
assembly-language programmers. 
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CONVENTIONS 


The following notations are used in Inside Macintosh to draw your attention to 
particular items of information: 


Reader's guide: Advice to you, the reader, that will help you decide whether 


or not you need to understand the material in a specific 
chapter or section. 


Note: An item of technical information that you may find interesting or 


useful. 


Warning: A point you need to be cautious about 


Assembly-language note: Information of interest to assembly-language 


programmers only. For a discussion of Macintosh 
assembly- language programming, see the chapter 
"Using Assembly Language". 


64K ROM note: A note that points out some difference between the 64K ROM 


[Not in ROM] 


and 128K ROM. 


Routines marked with the notation [Not in ROM] are not part of 
the Macintosh ROM. Depending on which System file the user has 
and on how complete the interfaces are in the development system 
you're using, these routines may or may not be available. 
They're available with Version 4.1 and later of the Macintosh 
System file and in programs developed with the Macintosh 
Programmer's Workshop. 


[Macintosh II] Routines marked with the name or names of specific models 


work only on those machines. 
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